feat(web): add web generator #285
Conversation
Codecov ReportAttention: Patch coverage is
✅ All tests successful. No failed tests found. Additional details and impacted files@@ Coverage Diff @@
## main #285 +/- ##
==========================================
- Coverage 72.14% 70.59% -1.56%
==========================================
Files 117 128 +11
Lines 9992 11011 +1019
Branches 597 644 +47
==========================================
+ Hits 7209 7773 +564
- Misses 2780 3231 +451
- Partials 3 7 +4 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
🎉 The code now dehydrates to the client so it can render without JavaScript! |
Wow 😵💫 and what about codetab |
|
It rehydrates and runs with JS, but if you don't have JS, you can still view the docs. I used React's SSRing |
|
@AugustinMauroy and I got search to finally work 🎉 |
avivkeller
force-pushed
the
feat/web/gen
branch
2 times, most recently
from
024bbea to
dbfe55d
Compare
|
@nodejs/nodejs-website @nodejs/web-infra |
You mean manually writing down the stability of each one of the modules? Noted... But how the current tooling does that if Makefile also uses only individual files? Or does it also fail currently for individual files? I don't recall tbh. |
See https://github.com/nodejs/node/blob/4102dcc2269d12cb576468370419b059c31e72b0/tools/doc/stability.mjs, which uses the generated |
I'd love to... but it's actually quite complex. If we use |
Became
Which is take more place. DO we have ability to detect this case and don't duplicate it or merge it |
I originally merged them, but we have so many different edge cases on node core, I'd rather follow-up with an issue adding:
Before implementing such a feature. It's a lot of work to resolve the edge cases, and I don't want that to break this, and block it from merging. |
What if we only handle the non-edge cases? Would that make sense? Also 
nit: Can Return not be in a <code> since it is not a property, but the return value? |
No, I don't think that would. The edge cases are headers that have slightly different descriptions/history/whatnot, and would require additional logic to merge / not to merge. You can't, in my eyes, handle the non-edge cases without accounting for the edge-cases, so it would be easier (IMO) to handle it all in a follow-up. |
|
FYI I made a new milestone, and will open / am opening follow-ups |
|
Oh hi @TheAlexLichter just wanted to randomly say thank you for chiming in here 🫶 |
|
@ovflowd Sure thing! 🙌 Glad I could help |
|
@nodejs/web-infra Is there anything else I missed that I still need to implement. Just waiting on a CODEOWNER review from y'all. We are almost there 🚀! |
There was a problem hiding this comment.
Feature-wise 
🚀 -- code wise, 👎
We need to add much more jsdocs, inline comments, extract regexes and things into constants and better simplify/cleanup the code.
Otherwise we will have a hug knowledge gap day one of what each logic means what it does and etc. I also appreciate exmaples on jsdocs. You can use Copilot or some Agentic stuff to help on that if it is massive 😅
| [SAMPLE], | ||
| SAMPLE, | ||
| {}, | ||
| { |
There was a problem hiding this comment.
This can be an inline object { run: async... }
| * | ||
| * @param {*} value - The value to convert to an ESTree node | ||
| */ | ||
| const toESTree = value => { |
There was a problem hiding this comment.
I'm pretty sure there's an utility on unist that already does that, no?
| value: entry.heading.data.name, | ||
| })); | ||
| .filter( | ||
| entry => entry.heading?.data?.text && entry.heading?.data?.depth < 4 |
There was a problem hiding this comment.
make 4 a constant and explain why 4 also put ?.text.length > 0 to make it explicit
| const parsed = getVersionFromSemVer(version); | ||
|
|
||
| let label = `v${parsed}`; | ||
| if (isLts) { |
There was a problem hiding this comment.
nit: separate assignemtns from conditions (empty lines)
| } | ||
|
|
||
| return { | ||
| value: getVersionURL(parsed, entry.api), |
There was a problem hiding this comment.
nit: assignt o constant after line 75, then short object notation return { value, label }
|
|
||
| let headingContent = text | ||
| ? getFullName(content.data, false) || | ||
| slice(content, (findText(content, ':')[0] ?? -1) + 1).node.children |
There was a problem hiding this comment.
This one line is quite convoluted, let's break this down and move to a dedicated function and document/explain what it does
| * @returns {number} - 2 if node is a type connector, 1 if node is a type reference, 0 otherwise | ||
| */ | ||
| const checkPossibleType = node => | ||
| node.type === 'text' && node.value === ' | ' |
There was a problem hiding this comment.
This could also be more documented / broken down
| export const parseListIntoProperties = node => { | ||
| const properties = []; | ||
|
|
||
| for (const item of node.children) { |
There was a problem hiding this comment.
I'd also appreciate if this could be more documented, broken down, simplified. Huge function.
| cells.push(createElement('td', prop.types.length > 0 ? prop.types : '-')); | ||
| cells.push(createElement('td', prop.desc.length > 0 ? prop.desc : '-')); | ||
|
|
||
| return prop.sublist |
There was a problem hiding this comment.
Dedicated function? or if else with push idk
| } | ||
|
|
||
| const returnStr = returnType ? `: ${returnType.type}` : ''; | ||
| const paramsStr = params |
|
(FYI I've stopped my review-mid-term, as I've seen the same pattern of lack of docs, code that could be cleaned-up split-up etc... and then I just realised better just adding my review and letting @avivkeller work on that 🙈) |
|
Thanks for the review! I'll get right on it! |
Fixes #7.
This PR adds the web generator.
Tasks / Issues
P1 – Must Complete Before Merge
P2 – Must complete before migration
P3 – Can Be Done in a Follow-up
mustachedependencyDataTagGet a preview
Footnotes
Add things as they appear, or leave review comments. ↩ ↩2 ↩3